Skip to content

docs: design study for #83 — delegation and key mapping - #87

Merged
thorwhalen merged 1 commit into
masterfrom
claude/design-doc-delegation-key-mapping
Aug 10, 2026
Merged

docs: design study for #83 — delegation and key mapping#87
thorwhalen merged 1 commit into
masterfrom
claude/design-doc-delegation-key-mapping

Conversation

@thorwhalen

Copy link
Copy Markdown
Member

Docs only. Makes the #83 investigation durable and citable, next to
dol_issue18_design.md (its inverse) and
dol_issue10_design.md.

Discussion #86 already captured this, but a discussion is easy to lose and awkward to cite from
a code review; misc/docs/ is where dol's design records live.

What it records

  • Two delegation routes, not oneStore.__getattr__ and DelegatedAttribute.__get__. A
    fix covering one is a silent no-op on the other, which is why several past fixes had to be
    applied twice.
  • The 13-package census, stated accurately. The defect is overwhelmingly latent — it
    bites only when a user applies a key codec — and 12 survey claims were refuted outright.
    An earlier downstream draft claimed the family was actively destroying data; it is not, and the
    record now says so explicitly.
  • Options A–F, each with the running-code evidence for its cost, including three that look
    right and are not:
    • wrapped_self has its own silent hole (degrades to the raw leaf when nothing holds a strong
      reference to the wrapper; the wrong answer is a plausible str where the leaf owns a
      prefix). Reproduced on CPython 3.10–3.14. Detectable, so it can at least be made loud.
    • Chain-walking free functions break on a non-Store layer — where the method form is right.
      dol's own instance (content_url) had the bug until fix: two delegation bugs in dol's own code (content_url, filesys key validation) #85.
    • "Capabilities as parallel Mappings" is broken as an attribute and correct by construction
      as a sibling store; those are different designs and get conflated.
  • §5 — the carry-forward list for a future redesign, which is the point of writing it down:
    the has-a/is-a choice is one decision rather than three symptoms; a wrapper must be able to
    express "this method takes a key"; the two routes must be unified; key mapping needs an inverse
    (inward→outward has no supported helper, so every adapter hand-rolls it); weakref backrefs are
    the wrong substrate for correctness; non-Store layers exist in the wild (dol ships a recipe
    for one); and "how many keyed methods does this force adapters to write?" is a design metric
    worth tracking — azuredol has ~0 and is the clean one.

Indexed from CLAUDE.md and misc/docs/dol_misc_docs_guide.md. Every file:line citation
verified against current source. Suite unchanged: 525 passed, 3 skipped.

Discussion #86 captured this, but a discussion is easy to lose and hard to cite from
code review. misc/docs/ is where dol's durable design records live, so this lands
next to dol_issue18_design.md (its inverse) and dol_issue10_design.md.

Records, with the running-code evidence for each:

- TWO delegation routes, not one -- Store.__getattr__ AND
  DelegatedAttribute.__get__. A fix covering one is a silent no-op on the other,
  which is why several past fixes had to be applied twice.
- The 13-package census, stated accurately: the defect is overwhelmingly LATENT
  (it bites only when a user applies a key codec), and 12 survey claims were
  refuted outright. An earlier downstream draft claimed the family was actively
  destroying data; it is not, and the record says so.
- Options A-F with what each actually costs:
  A wrapped_self  -- has its own silent hole: degrades to the raw leaf when nothing
                     holds a strong reference to the wrapper, and where the leaf owns
                     a prefix the wrong answer is a plausible str. CPython 3.10-3.14.
                     Detectable via the KeysView probe, so it can be made loud.
  B declarative   -- dol already ships this (ingoing_key_methods), untested and
                     broken for leaf-defined methods. The reflective test is the part
                     that holds, not the registry.
  C free funcs    -- break on a non-Store layer, where the method form is right.
                     dol's own instance (content_url) had the bug until #85.
  D rebind        -- rejected in dol_issue18_design.md with evidence; binds to the
                     INNERMOST wrap, so it misses the Pipe case it exists to fix.
  E parallel maps -- broken as an ATTRIBUTE (a wrapper does not re-wrap one),
                     correct by construction as a sibling STORE keyed through
                     __getitem__. The only option needing no resolution primitive.
  F is-a          -- the terminal fix; dissolves #83, #18 and #6 together.

Section 5 is the explicit carry-forward list for a future redesign: the has-a/is-a
choice is one decision not three; a wrapper must be able to express "this method
takes a key"; the two routes must be unified; key mapping needs an inverse
(inward->outward has no supported helper); weakref backrefs are the wrong substrate
for correctness; non-Store layers exist in the wild; and "how many keyed methods does
this force adapters to write?" is a design metric worth tracking (azuredol has ~0 and
is clean).

Indexed from CLAUDE.md and dol_misc_docs_guide.md. All file:line citations verified
against the current source.
@thorwhalen
thorwhalen merged commit 1f0a84e into master Aug 10, 2026
12 checks passed
@thorwhalen
thorwhalen deleted the claude/design-doc-delegation-key-mapping branch August 10, 2026 17:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant